Add a new tenant

The first step to creating a new tenant is to create a database in SQL Server, and then prepare it for use by applying the 'DB UPGRADE' program. Once that is complete, use the 'Tenants' screen in IPS Manager to add a new tenant to your IPS Server deployment.

Tenant database creation and DBUPGRADE

In an SQL Server management tool, create a new database.

As an alternative, you may have been provided a starter database (as a BAK file) by Quorum Software. In this case, use the 'Restore Database' option in SQL Server.

The database name is at your choice; you will need to enter the name into the tenant configuration in IPS Manager.

The two essential settings for the new database are:

• Collation: Latin1_General_100_CI_AS_WS
• Compatibility level: SQL Server 2016 (130)

Next, run DBUPGRADE. This requires Microsoft Office (version 2010 or later) to be installed in the machine where the upgrade program is running (this can be any machine with network access to the SQL Server machine).

If you have used a starter database provided by Quorum Software, please check if this upgrade step is required. The upgrade program will temporarily grow the SQL Server logs due to creation of recovery log data; if the operational database Recovery Model setting is not 'Simple' then it is recommended to temporarily switch it to 'Simple' during the upgrade, in order to avoid the possibility of disk space overflow.

Use the 'DBUpgrade' program (downloadable from https://clients.aucerna.com/products/downloads). Unzip 'DBUpgrade_16.5.x.xxxx', where 'x' is the update number and 'xxxx' is the build number (the zip filename may have the version number without full stops 'dbupgrade_165xxxxx').

Note that the DBUPGRADE version and update numbers must be what are required for the version of IPS Server/Planning Space that you are installing. If you are not installing the current latest version, check with Quorum Software Support for what is needed.

Note: It is recommended to disable realtime antivirus software if you experience slow performance of the DBUPGRADE programs. Version 16.5 Update 7 and later contain code improvements which should make this problem very unlikely.

Run the executable 'Palantir.DBUpgrade.exe'.

The SQL Server account that you use here needs to have the permission role 'db_owner' for the tenant database. If the SQL Server account is linked to your current Windows login, click the box 'Use Trusted Connection'. Otherwise, type in the Username and Password of a SQL Server-authenticated account.

In the 'Server' field, click the down arrow to show a list of the SQL Server instances detected in the current Windows domain, and select the name of the SQL Server instance that you are using. You can also type the instance name into the input box.

In the 'Database' field, you can type in the name of the tenant database, or click the down arrow to show the list of databases found in the SQL Server instance (note that you may not see any list, depending on the VIEW permissions of the SQL Server account that is being used).

If the SQL Server is configured with a self-signed or trusted certificate, you can enable SSL-based encryption by ticking the box 'Use transport encryption'. If you tick 'Trust server certificate' then the DBUPGRADE program will trust any certificate that is offered by the SQL Server machine; otherwise the Windows certification protocols must be satisfied.

Check box 'Check Excel dependencies': You should keep the default setting (checked).

Click the 'Connect' button, and the program will check that the database is ready to be upgraded, then click the 'Next' button to start the upgrade process.

A log file will be created at: 'C:\Users\{Username}\AppData\Local\Palantir\{DatabaseName}.txt'.

Set the database permissions for the SQL Server account

The SQL Server account used by IPS Server must have permissions on the new database as follows: 'db_datareader', 'db_datawriter', and 'pes_datawriter' (the last permission type is added by the DBUPGRADE program).

Create a new tenant in IPS Manager

Open IPS Manager, click 'Tenants' on the left-hand menu, and click the 'Add tenant' button to open a dialog:

Type in a name for the new tenant. The name is at your choice; this name will appear in the URL for running Planning Space, so the name should be appropriate, not too long, and easy to type. Click the 'Ok' button.

Important: Rules for tenant naming
- A tenant name can have a maximum of 50 characters, it must start with a letter, and it can only contain letters, numbers, dashes, and underscores.
- The tenant name cannot clash with any resource path that is used by IPS Server. These are: 'admin', 'license', 'licenseserver', and 'monitor'.
- Tenant names are not case-sensitive, hence a tenant named 'europe' could also be referred to by 'Europe' or 'EUROPE', etc. These are all the same tenant name.

This creates a new entry ('UAT-testing' in this example) in the list of tenants:

The new tenant's data source (database), 'Cluster shared temp folder' and 'Identity Provider' (if ADFS-based authentication is used) need to be configured now.

Assign the tenant database

Important: Authentication of the connection to the tenant data source can use the IPS Service Account (with Windows authentication) or an SQL Server-authenticated account. SQL authentication is recommended, because it allows the cluster shared Temp folder to be located anywhere on the network. However, if the IPS Service Account is used then the Temp folder must be located on the same machine as the SQL Server; this is a security restriction imposed by SQL Server to restrict bulk insert operations. This security restriction can be avoided, and the shared Temp folder placed anywhere on the network, by means of more complex system configuration: Kerberos delegation must be configured, and required SETSPN commands must be performed by a Domain Administrator. Please contact Quorum Software Support for instructions for running IPS Server and SQL Server in this configuration.

Click the 'Assign' button to open the tenant 'Assign data source' dialog:

Select or enter a server name: either type the name of the SQL Server instance where the tenant database is stored, or click the down arrow which will show a list of the SQL Server instances detected in the current Windows domain.

Enter information to login to server: Select 'Use IPS Service account' if you have created a SQL Server account that is linked to the IPS Service Account in Windows; otherwise select 'Use SQL user name and password' and type in the username and password of a SQL Server-authenticated account.

Connection properties: If the SQL Server is configured with a self-signed or trusted certificate then tick 'Use transport encryption' to enable SSL-based encryption of traffic between the IPS Server machine(s) and the SQL Server machine. If you tick 'Trust server certificate' then the IPS Server machines will automatically trust any certificate that is offered by the SQL Server machine; otherwise the Windows certification protocols must be satisfied.

Select the database on the server: You can type in the database name, or click the down arrow to show the list of databases found in the SQL Server instance (note: the list function may not work, depending on the 'VIEW' permissions of the SQL Server account that you are using, in this case you must type in the name). Click the 'Test' button to verify the database can be accessed and is ready to be used.

Click the 'Ok' button to save the information, and close the dialog.

Set the Cluster shared temp folder

Enter the path for the 'Cluster shared temp folder' in the input box.

(See Cluster shared Temp folder.)

Set the Identity Provider and Token Lifetime

These settings are required when an Identity Provider server or service is used to authenticate SAML2 user accounts.

'Token lifetime' has a default value of 15 minutes. See Bearer Token lifetime.

For 'Identity Provider', click the 'Configure' button and follow the instructions at Identity Provider (IdP) setup.

Authentication methods

Save the settings for the new tenant

Click the 'Save all changes' button to save the settings for the new tenant.

Important: An initial administrator user is created for the tenant, with username 'Administrator' and password 'Administrator'.

Available applications

The initial settings under 'Available applications' are that client access to all applications is disabled.

Before applications can be used, product licenses need to be available to users. See Product licensing for details.

To enable access to applications, tick the box for 'PlanningSpace' and/or 'cx SUITE', and click the 'Save all changes' button.